Move documentation to inline comments: GtkMessageDialog

Also, add a note about GTK_BUTTONS_OK, GTK_BUTTONS_YES_NO
and GTK_BUTTONS_OK_CANCEL are discouraged by the GNOME HIG.

https://bugzilla.gnome.org/show_bug.cgi?id=597865

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
new file mode 100644 (file)
index 0000000..1f9678b
--- /dev/null
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -0,0 +1 @@
+gtkmessagedialog.sgml

diff --git a/docs/reference/gtk/tmpl/gtkmessagedialog.sgml b/docs/reference/gtk/tmpl/gtkmessagedialog.sgml
deleted file mode 100644 (file)
index f2122cb..0000000
--- a/docs/reference/gtk/tmpl/gtkmessagedialog.sgml
+++ /dev/null
@@ -1,213 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkMessageDialog
-
-<!-- ##### SECTION Short_Description ##### -->
-A convenient message window
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-#GtkMessageDialog presents a dialog with an image representing the type of 
-message (Error, Question, etc.) alongside some message text. It's simply a 
-convenience widget; you could construct the equivalent of #GtkMessageDialog 
-from #GtkDialog without too much effort, but #GtkMessageDialog saves typing.
-</para>
-
-<para>
-The easiest way to do a modal message dialog is to use gtk_dialog_run(), though
-you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically
-makes the dialog modal and waits for the user to respond to it. gtk_dialog_run()
-returns when any dialog button is clicked.
-<example>
-<title>A modal dialog.</title>
-<programlisting>
- dialog = gtk_message_dialog_new (main_application_window,
-                                  GTK_DIALOG_DESTROY_WITH_PARENT,
-                                  GTK_MESSAGE_ERROR,
-                                  GTK_BUTTONS_CLOSE,
-                                  "Error loading file '&percnt;s': &percnt;s",
-                                  filename, g_strerror (errno));
- gtk_dialog_run (GTK_DIALOG (dialog));
- gtk_widget_destroy (dialog);
-</programlisting>
-</example>
-</para>
-
-<para>
-You might do a non-modal #GtkMessageDialog as follows:
-<example>
-<title>A non-modal dialog.</title>
-<programlisting>
- dialog = gtk_message_dialog_new (main_application_window,
-                                  GTK_DIALOG_DESTROY_WITH_PARENT,
-                                  GTK_MESSAGE_ERROR,
-                                  GTK_BUTTONS_CLOSE,
-                                  "Error loading file '&percnt;s': &percnt;s",
-                                  filename, g_strerror (errno));
-
- /* Destroy the dialog when the user responds to it (e.g. clicks a button) */
- g_signal_connect_swapped (dialog, "response",
-                           G_CALLBACK (gtk_widget_destroy),
-                           dialog);
-</programlisting>
-</example>
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GtkDialog
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GtkMessageDialog ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GtkMessageDialog:buttons ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMessageDialog:image ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMessageDialog:message-type ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMessageDialog:secondary-text ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMessageDialog:secondary-use-markup ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMessageDialog:text ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMessageDialog:use-markup ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMessageDialog:message-border ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkMessageDialog:use-separator ##### -->
-<para>
-
-</para>
-
-<!-- ##### ENUM GtkMessageType ##### -->
-<para>
-The type of message being displayed in the dialog.
-</para>
-
-@GTK_MESSAGE_INFO: Informational message
-@GTK_MESSAGE_WARNING: Nonfatal warning message
-@GTK_MESSAGE_QUESTION: Question requiring a choice
-@GTK_MESSAGE_ERROR: Fatal error message
-@GTK_MESSAGE_OTHER: None of the above, doesn't get an icon
-
-<!-- ##### ENUM GtkButtonsType ##### -->
-<para>
-Prebuilt sets of buttons for the dialog. If 
-none of these choices are appropriate, simply use %GTK_BUTTONS_NONE
-then call gtk_dialog_add_buttons().
-</para>
-
-@GTK_BUTTONS_NONE: no buttons at all
-@GTK_BUTTONS_OK: an OK button
-@GTK_BUTTONS_CLOSE: a Close button
-@GTK_BUTTONS_CANCEL: a Cancel button
-@GTK_BUTTONS_YES_NO: Yes and No buttons
-@GTK_BUTTONS_OK_CANCEL: OK and Cancel buttons
-
-<!-- ##### FUNCTION gtk_message_dialog_new ##### -->
-<para>
-
-</para>
-
-@parent: 
-@flags: 
-@type: 
-@buttons: 
-@message_format: 
-@Varargs: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_message_dialog_new_with_markup ##### -->
-<para>
-
-</para>
-
-@parent: 
-@flags: 
-@type: 
-@buttons: 
-@message_format: 
-@Varargs: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_message_dialog_set_markup ##### -->
-<para>
-
-</para>
-
-@message_dialog: 
-@str: 
-
-
-<!-- ##### FUNCTION gtk_message_dialog_set_image ##### -->
-<para>
-
-</para>
-
-@dialog: 
-@image: 
-
-
-<!-- ##### FUNCTION gtk_message_dialog_get_image ##### -->
-<para>
-
-</para>
-
-@dialog: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_message_dialog_format_secondary_text ##### -->
-<para>
-
-</para>
-
-@message_dialog: 
-@message_format: 
-@Varargs: 
-
-
-<!-- ##### FUNCTION gtk_message_dialog_format_secondary_markup ##### -->
-<para>
-
-</para>
-
-@message_dialog: 
-@message_format: 
-@Varargs: 
-
-

diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index b8b5e3359459633019ed4cb1a4571ebfb45927ae..7c577c70b7bfb7e4a0852ef711db0ca6228480e4 100644 (file)
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -208,6 +208,16 @@ typedef enum
   GTK_MENU_DIR_PREV
 } GtkMenuDirectionType;
 
+/**
+ * GtkMessageType:
+ * @GTK_MESSAGE_INFO: Informational message
+ * @GTK_MESSAGE_WARNING: Nonfatal warning message
+ * @GTK_MESSAGE_QUESTION: Question requiring a choice
+ * @GTK_MESSAGE_ERROR: Fatal error message
+ * @GTK_MESSAGE_OTHER: None of the above, doesn't get an icon
+ *
+ * The type of message being displayed in the dialog.
+ */
 typedef enum
 {
   GTK_MESSAGE_INFO,

diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index 71a4098b54a4133ef7dfb20399067ae90fbaca50..18adeea2a096fb8711fc5773e773cc6c2a65e422 100644 (file)
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -40,6 +40,53 @@
 #include "gtkprivate.h"
 #include "gtkalias.h"
 
+/**
+ * SECTION:gtkmessagedialog
+ * @Short_description: A convenient message window
+ * @Title: GtkMessageDialog
+ * @See_also:#GtkDialog
+ *
+ * #GtkMessageDialog presents a dialog with an image representing the type of
+ * message (Error, Question, etc.) alongside some message text. It's simply a
+ * convenience widget; you could construct the equivalent of #GtkMessageDialog
+ * from #GtkDialog without too much effort, but #GtkMessageDialog saves typing.
+ *
+ * The easiest way to do a modal message dialog is to use gtk_dialog_run(), though
+ * you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically
+ * makes the dialog modal and waits for the user to respond to it. gtk_dialog_run()
+ * returns when any dialog button is clicked.
+ * <example>
+ * <title>A modal dialog.</title>
+ * <programlisting>
+ *  dialog = gtk_message_dialog_new (main_application_window,
+ *                                   GTK_DIALOG_DESTROY_WITH_PARENT,
+ *                                   GTK_MESSAGE_ERROR,
+ *                                   GTK_BUTTONS_CLOSE,
+ *                                   "Error loading file '&percnt;s': &percnt;s",
+ *                                   filename, g_strerror (errno));
+ *  gtk_dialog_run (GTK_DIALOG (dialog));
+ *  gtk_widget_destroy (dialog);
+ * </programlisting>
+ * </example>
+ * You might do a non-modal #GtkMessageDialog as follows:
+ * <example>
+ * <title>A non-modal dialog.</title>
+ * <programlisting>
+ *  dialog = gtk_message_dialog_new (main_application_window,
+ *                                   GTK_DIALOG_DESTROY_WITH_PARENT,
+ *                                   GTK_MESSAGE_ERROR,
+ *                                   GTK_BUTTONS_CLOSE,
+ *                                   "Error loading file '&percnt;s': &percnt;s",
+ *                                   filename, g_strerror (errno));
+ *
+ *  /&ast; Destroy the dialog when the user responds to it (e.g. clicks a button) &ast;/
+ *  g_signal_connect_swapped (dialog, "response",
+ *                            G_CALLBACK (gtk_widget_destroy),
+ *                            dialog);
+ * </programlisting>
+ * </example>
+ */
+
 #define GTK_MESSAGE_DIALOG_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GTK_TYPE_MESSAGE_DIALOG, GtkMessageDialogPrivate))
 
 typedef struct _GtkMessageDialogPrivate GtkMessageDialogPrivate;

diff --git a/gtk/gtkmessagedialog.h b/gtk/gtkmessagedialog.h
index 1bb1ec5fc2f0abf83595c89434f05317348ad62c..c46c7b3db72b284f6d44ecc68e0dc091c6498b54 100644 (file)
--- a/gtk/gtkmessagedialog.h
+++ b/gtk/gtkmessagedialog.h
@@ -36,15 +36,6 @@
 
 G_BEGIN_DECLS
 
-typedef enum
-{
-  GTK_BUTTONS_NONE,
-  GTK_BUTTONS_OK,
-  GTK_BUTTONS_CLOSE,
-  GTK_BUTTONS_CANCEL,
-  GTK_BUTTONS_YES_NO,
-  GTK_BUTTONS_OK_CANCEL
-} GtkButtonsType;
 
 #define GTK_TYPE_MESSAGE_DIALOG                  (gtk_message_dialog_get_type ())
 #define GTK_MESSAGE_DIALOG(obj)                  (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_MESSAGE_DIALOG, GtkMessageDialog))
@@ -77,6 +68,34 @@ struct _GtkMessageDialogClass
   void (*_gtk_reserved4) (void);
 };
 
+/**
+ * GtkButtonsType:
+ * @GTK_BUTTONS_NONE: no buttons at all
+ * @GTK_BUTTONS_OK: an OK button
+ * @GTK_BUTTONS_CLOSE: a Close button
+ * @GTK_BUTTONS_CANCEL: a Cancel button
+ * @GTK_BUTTONS_YES_NO: Yes and No buttons
+ * @GTK_BUTTONS_OK_CANCEL: OK and Cancel buttons
+ *
+ * Prebuilt sets of buttons for the dialog. If
+ * none of these choices are appropriate, simply use %GTK_BUTTONS_NONE
+ * then call gtk_dialog_add_buttons().
+ * <note>
+ *  Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO
+ *  and %GTK_BUTTONS_OK_CANCEL are discouraged by the
+ *  <ulink url="http://library.gnome.org/devel/hig-book/stable/">GNOME HIG</ulink>.
+ * </note>
+ */
+typedef enum
+{
+  GTK_BUTTONS_NONE,
+  GTK_BUTTONS_OK,
+  GTK_BUTTONS_CLOSE,
+  GTK_BUTTONS_CANCEL,
+  GTK_BUTTONS_YES_NO,
+  GTK_BUTTONS_OK_CANCEL
+} GtkButtonsType;
+
 GType      gtk_message_dialog_get_type (void) G_GNUC_CONST;
 
 GtkWidget* gtk_message_dialog_new      (GtkWindow      *parent,